.TH EXP "1" "March 2014" "exp" "User Commands"
.SH NAME
expansive \- Embedthis Expansive -- Fast, Flexible Static Web Site Generator
.SH SYNOPSIS
.B exp
    \fB--abort\fR
    \fB--chdir directory\fR
    \fB--clean\fR
    \fB--listen IP:PORT\fR
    \fB--log path:level\fR
    \fB--noclean\fR
    \fB--norender\fR
    \fB--nowatch\fR
    \fB--quiet\fR
    \fB--trace path:level\fR
    \fB--verbose dir\fR
    \fB--version\fR
    \fBcommands ...\fB
.SH ""
.B Commands:
    clean
    deploy [directory]
    edit key[=value]
    init
    mode [debug|release|...]
    render
    serve
    watch
    FILES ...
    <CR>
.RE
.SH DESCRIPTION
\fBExpansive\fR is a fast and flexible static web site generator.
It quickly creates HTML pages from layouts, partials and content pages.
Expansive brings dynamic content to static web sites.

.PP
Expansive includes flexible tooling so you can build your site in development mode and 
painlessly switch to production mode for release. It will minify, compress and bundle your site for easy deployment.

.PP
.SH WHY EXPANSIVE?
There are many web site site generators, why another one? Most existing site generators are slow, often painfully 
slow.  When creating or managing a web site, you need tools that do not delay the creative design process. 
They need to be as fast as possible. Expansive is designed to be fast, without sacrificing features.

.SH FEATURES
Expansive generates static web sites from pages, layouts, partials and scripts. It
has the following major features:

    . Javascript templates for dynamic content
    . Layout pages to define the look and feel of site
    . Partial pages to include replicated content
    . Per-page meta data to control layouts and partials
    . Integrated web server to serve content
    . Watches for changes and automatically render site
    . Scripting support via change events
    . Automatic sitemap creation
    . Complete tooling for minifying, compression and bundling your site
    . Content transition pipeline
    . Open plugin architecture

.SH NICE PARTS
While Expansive has a strong feature set, there are some characteristics that make Expansive particularly sweet.

    . Fast, fast, fast
    . Embedded Ejscript for server-side Javascript in every page
    . Easy to create and install new plugins
    . Great diagnostics when things go wrong

.PP
.SH BASIC USAGE
.PP
To prepare a directory for expansive and create an expansive.json configuration file:

    expansive init

To install new plugins to transform content, use the Pak command. The exp-less compiles *.less into css. 

    pak install exp-less

To render a site from 'contents' into 'dist'. This processes web pages under the 'contents'
directory into the 'dist' directory for production. 

    expansive render

To serve content and watch for changes

    expansive serve

or
    expansive

To watch for changes but not serve

    expansive watch

To render a matching set of files

    expansive contents/index.html
    expansive contents/manual

To deploy a rendered site

    expansive deploy directory

To clean the rendered site under 'dist'

    expansive clean

.PP
.SH DIRECTORIES
Expansive uses the following directories:

    contents    Souce web content to be processed
    dist        Final output directory containing the rendered documents
    files       Files to be copied and not processed
    layouts     For master page layouts
    partials    For partial web pages that can be included by other pages

These directories can be modified via meta 'directories' collection in the package.json file.

.SH PROCESSING
Expansive operates by processing web pages from the 'contents' and 'lib' directories. It uses layout pages from 
the 'layouts' directory and includes partial pages from the 'partials' directory. 
Raw files may be copied from the 'files' directory. Documents are rendered to the 'dist' output directory.

.SH CONFIGURATION
Expansive is controlled by an 'expansive.json' configuration file. This defines top level configuration for the site and 
controls how Expansive renders the site. An expansive.json file must be present for Expansive to render content.
.PP
To prepare a new site to use Expansive, run:

    expansive init

.PP
This creates an expansive.json and package.json file. The expansive.json file controls Expansive execution. The package.json
file is used by the Pak manager when installing or managing extension packages.
.PP
.RS 5
 {
     meta: {
         site: 'http://example.com',
         sitemap: {
            files: [
                '**.html',
                !**unsupported.html'
            ]
        }
     },
     control: {
         copy: [ 'images' ],
         listen: '127.0.0.1:4800'
     }
 }
.RE
.PP
Expansive uses a liberal json format that permits comments, unquoted property keys and use of multi-line quotes. The 
'meta' contents of the expansive.json file are added to the Expansive meta data collection that is provided to every page, 
layout and partial page. The 'control' collection has properties that control the operation of Expansive. These values
are made available to web pages via the 'expansive.control' property.

.PP
In the 'control' section, the 'documents' array defines the set of patterns to select documents from the 'contents'
directory for processing.  The 'copy' array defines a set of patterns to select files to copy without processing. 
The copy patterns are relative to the 'contents' directory.

.SH DYNAMIC CONTENT
Expansive uses embedded Javascript in web pages to fully support dynamic content.  Scripts can be embedded via the special
Expansive tag '<@ ...  @>'. This will run the script when the page is rendered and replace the script with rendered data.
When the script runs, the 'this' object is set to the 'expansive' object for easy access to Expansive methods. See SCRIPTING
below for more details. 
.PP
For example, to render the current date in a document:

 <p>Today is <@ write(Date()) @>

The write function is used to render data to be used in place of the <@ @> element.  You can use 'writeSafe' to HTML
escape the data before writing. You can also use a simpler form <@= that means use the result of the Javascript
expression, HTML escapse the data and then write it. For example:

 <p>Today is <@= Date() @>

Even simpler, you can use an abbreviated @= variable to emit the value of a Javascript variable. For example:

 <p>Site URL is @={meta.site}</p>

The top URL of the site may be abbreviated as '@~'.

.SH TRANSFORMATIONS
Expansive will interpret document extensions and automatically transform content from one format to another.  For example,
the filename 'instructions.html.md' tells Expansive that the data is in Markdown format via the '.md' extension and it
should be converted to 'html'.  Expansive will examine each nested extension and process the document until it reaches an
extension for which there is no further transformations defined.
.PP
Expansive uses the '.exp' extension to specify the document has embedded Javascript. For example:

     index.html.md.exp

This means the file has Embedded Javascript in a Markdown file that will be compiled to HTML. Expansive will process
this by first running the embedded Javascript, then piping the result through the Markdown filter and finally saving the
result as 'index.html'.
.PP
The transformation pipeline for specific extensions can be overridden via the 'expansive.transforms' meta property.

.SH PLUGINS
Expansive may be extended via plugins that provide transformations and additional scripting capability.
Plugins are installed using the Pak manager via 'pak install NAMES...'. Once installed, expansive will load all
installed plugin packages.

.SH USEFUL PLUGINS
Here are some of the more useful Expansive plugins:
.TP 10
exp-bash
Run shell scripts and capture the output.
.TP 10
exp-css
Process CSS files to add browser specific prefixes and minify the output. Requires 'autoprefixer' and 'recess' to be installed.
.TP 10
exp-esp
Compile ESP web pages and applications.
.TP 10
exp-gzip
Compress final output using gzip. Files are rendered with a 'gz' extension.
.TP 10
exp-js
Process Javascript files to mangle and minify. Requires 'uglify' to be installed.
.TP 10
exp-less
Process Less stylesheets into CSS. Requires 'recess' to be installed.
.TP 10
exp-md
Process Markdown files and emit html.
.TP 10
exp-sass
Process SASS files into CSS. Requires "sass" to be installed. 
.PP
Many plugins can be customized by passing configuration to the plugin via expansive.json file. For example:
To request that all Javascript files be minified, use a '.min.js' extension, and be compressed but not managed:
.PP
 {
     services: {
         'minify-js': {
             compress: true,
             mangle: true,
             dotmin: true
         }
     }
 }

.PP 
See specific plugin documentation for the configuration options for each plugin.

.SH LAYOUTS
A layout page defines the top level HTML content for a set of pages.  The layout defines the format, look and feel of the
web site so that each pages does not need to replicate this content. Document pages nominate a layout page to
use, and the layout page then wraps the content page to create a composite page. 
The '<@ content @>' tag in the layout is replaced with the web page content after separating the page meta data.
.PP
There can be multiple layout pages and the default layout is called 'default.html.exp'. This may be modified by setting
the 'layout' meta property to an alternate layout name. Set to '' to disable layout processing.
Layout pages may nest, i.e. may use other layout pages.  Layout pages can use any desired transformation file extension.

.RS 5
 <!DOCTYPE html>
 <html lang="en">
 <head>
     <title><@= meta.title @></title>
     <link href="css/api.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
     <div class="content">
         <@ content @>
     </div>
 </body>
 </html>
.RE
.PP

.SH PARTIALS
Web pages often need to have content that is common across a set of pages. Expansive supports this via partial pages that
can be included by any page, layout or other partial page. A page specifies a partial by using the 'partial' Javascript
function. For example:

 <@ partial('header') @>

The partial function will search for a file starting with 'header.html' in the 'partials' directory.  Partials are
transformed according to their extension. If a partial called 'header.html.md.exp' was found, then it will be first
transformed by running the embedded Javascript, then piping the output into the Markdown to create html data that 
will then be included in place of the original partial tag.

.PP
Partials can be nested, in that a partial page may include another parital page to any depth.

.SH META DATA
Pages, layouts and partials can define meta data at the top of the file via a Javascript literal.  Meta data is passed to
the Javascript execution context for each page, layout and partial where scripts can examine and use in rendering pages.
.PP
.RS 5
 {
    draft: true,
    navigation: 'blog',
 }
 <h1>Page Header</h1>

.RE
The meta data is added to the current meta data collection from the expansive.json file and passed to the layout page, 
partials pages and content pages. The meta data can be accessed via the global 'meta' Javascript variable.

.PP
Meta data is inherited and aggregated as Expansive processes a web site directory. In each directory, a site may 
define an 'expansive.json' file that provides additional meta data for that directory level. The meta data from 
upper directories is passed down to lower directories. In this manner upper levels can define the parameters for 
subdirectories in the site. Meta data is never passed back up the tree.

.SH META PROPERTIES
Expansive defines a rich set of meta properties for you to use in your pages:
.TP 12
date
Generation date of the document.
.TP 12
description
Description of the web site. Sourced from the 'description' property in the package.json file.
.TP 12
dest
Final destination name of the rendered document or file in the 'dist' directory.
.TP 12
document
Input file name of the document being processed. For partials and layouts, this is set to the invoking document.
.TP 12
extension
The extension of the public document filename.
.TP 12
extensions
The set of extensions on the original input document.
.TP 12
from
The filename extension being processed by the current transformation.
.TP 12
isLayout
True if a layout is being processed.
.TP 12
isPartial
True if a partial page is being processed.
.TP 12
layout
Layout page in use. Set to '' if no layout being used.
.TP 12
mode
Index name in the pak.modes property. The selected property collection is copied up to the top level of the meta data.
This may be used to select a "debug" or "release" configuration.
.TP 12
partial
Name of the partial page being processed.
.TP 12
path
Destination filename of the document relative to the dist directory.
.TP 12
service
Name of the transformation service being run.
.TP 12
site
URL for the home page of the web site.
.TP 12
sitemap
Control what files to include in a sitemap. If defined, Expansive will by default include all HTML files in the sitemap.
To change the file set included in the sitemap, define a 'files' property with an array of patterns in the sitemap object.
.RS 5

       sitemap: {
          files: [ '**.html', '!draft.html' ],
       }
.RE
.TP 12
source
Current input source file being processed. May be a document, partial, layout or any input resource file. Includes the
    contents, lib, layouts or partials directory.
.TP 12
sourcePath
Source filename relative to the contents, lib, layouts, or partials directories.
.TP 12
title
Title of the web site. Sourced from the 'title' property in the package.json file.
.TP 12
to
The destination filename extension after processing by the current transformation.
.TP 12
top
URL for the top level home page of the site.
.TP 12
url
URL for the current page.

.SH EXPANSIVE CONTROL
Expansive defines a set of control properites in the meta.expansive property. These are originally sourced from the 'control' property in the 'expansive.json' file.
.TP 12
copy
Array of patterns to copy without processing. The patterns may include "*" or "**". If a directory is specifed, all files
under the directory are copied. The files are relative to the 'contents' directory.
.TP 12
documents
Array of patterns to process. The patterns may include "*" or "**". If a directory is specifed, all files
under the directory are processed. The files are relative to the 'contents' directory.
.TP 12
files
Array of directories containing raw content to copy to 'dist' without processing. By default, contains 'files'.
.TP 12
listen
Address on which to listen for HTTP requests. May be just a port number.
.TP 12
script
Script to evaluate to inject code into the Javascript global execution context.
.PP
.TP 12
transforms
Hash of extension mappings to a list of transform services for those mappings. Mappings are in the form 'ext -> ext'.
For example: 

 transforms: {
    'less -> css': [ 
        'compile-less', 
        'prefix-css', 
        'minify-css', 
        'compress' 
    ]
 }

Some of the standard service names are: compile-esp, compile-less, compile-markdown, compile-sass, compress, minify-css, minify-js, prefix-css, shell.
 
.TP 12
watch
Time in milliseconds to wait between checking for rendering.

.SH CREATING PLUGINS
Expansive plugins are created using the Pak utility (https://embedthis.com/pak) and published to the Pak Catalog at
(https://embedthis.com/catalog/). The plugin contains an expansive.json file that includes transforms relevant to the plugin.
For example:

 {
    expansive: {
        transforms: {
            name:   'my-transform',
            mappings:  {
                ext1: 'ext2',
            },
            script: '
                function transform(contents, meta, service) {
                    return transformed data
                }
            '
        }
    }
 }
.PP

The plugin specifies a one or more transformations via the 'transforms' collection. Each transform definition provides an
implemention of a transform service. The 'name' property specifies the transform service name. The service name provides
an abstract name for which multiple plugins may provide the implementation.
.PP
The 'mappings' property specifies a set of the input and output filename extensions used when transforming documents.
If all extensions are supported, set the value to '*'. The value may be an arrays if multiple extensions 
are supported. Extensions may be multipart, for example: 'min.js'.
.PP
The transform script should define a global 'transform' function that will be invoked for matching content.  It is invoked
with the 'contents' to transform (String), the meta data collection and the service object that contains service options.
The function should return the transformed data.
.PP
A plugin may also define other Javascript functions and variables in 'script' that will be injected into the global scope of
Expansive when it executes.
.PP
Web sites may configure services via properties in the expansive.json. For example:

 {
    services: {
        compress: false
        minfiy-css: {
            minify: true
        }
    }
 }
.PP
Configuration for a service can be specified in a property collection named for the service. If the service name is set to false, the service is disabled. See the plugin specific README documentation for supported configuration properties for each service.

.SH SCRIPTING
Expansive defines a Javascript global "expansive" to access and manage Expansive services. This object provides the following
methods:

.TP
addItems(collection, items)
Add items to a named collection. Collections are globally defined and reset at the start of processing for each document.
Documents, partials and layouts can inject items into collections for sharing to other documents. Items may be a string
or an array of strings. Items are uniquely added to the collection.
.TP
getFiles({key: value})
To return a list of matching documents that have meta data matching the specified keys and values.
.TP
getFileMeta(filename)
To return the meta data specified in the given file.
.TP
getItems(collection)
Return the items in a named collection as an Array.
.TP
removeItems(collection, items)
Remove the specified items from the named collection.
.TP
renderScripts
Render all scripts added to the 'scripts' collection via 'addItems'. This permits documents, partials and layouts to 
require Javascripts and have them emitted uniquely by a partial. Requires the exp-js plugin.
.TP
renderStyles
Render all stylesheets added to the 'styles' and 'inline-styles' collections via 'addItems'. This permits documents, 
partials and layouts to require stylesheets and have them emitted uniquely by a partial. Requires the exp-css plugin.
.TP
trace(tag, msg...)
To emit console trace while processing.

.SH COMMANDS
.TP
clean
Remove rendered content from the 'dist' output directory.
.TP
deploy
Deploy rendered content to a directory. This by default copies 'dist', 'cache', 
and expansive.json to 'deploy'.
.TP
init
Initialize a directory by creating an 'expansive.json' configuration file.
.TP
install
Install a plugin from the Pak catalog.
.TP
list
List the installed and uninstalled plugins and packages. 
.TP
render
Render the site by processing files from 'contents', 'layouts', 'partials' and 'files' into the 'dist' output directory.
.TP
uninstall
Uninstall a plugin from the expansive.json plugin list. The plugin remains in the local Pak cache.
.TP
upgrade
Upgrade a plugin version in the local Pak cache.
.TP
watch
Watch for changes to 'contents', 'layouts' and 'partials' and render the modified files. Changes to 'layouts' or 
'partials' will cause the entire site to be rendered.
.TP
serve
Serve the web site. 
By default Expansive will listen on port 4000. This can be modified via the 'listen' property in the meta collection.
Running expansive without any arguments is the same as "expansive serve".
.TP
patterns ...
Providing a list of patterns to filter the set of documents to render.  Expansive will render only the documents that
begin with the given patterns.


.SH OPTIONS
.TP 10
\fB\--abort\fR
Abort processing on render errors.

.TP 10
\fB\--chdir directory\fR
Change to directory before running.

.TP 10
\fB\--clean\fR
Clean output "dist" directory first.

.TP 10
\fB\--listen IP:PORT URI\fR
Change the port on which Expansive will listen. Can omit the IP portion and only specify a port.

.TP 10
\fB\--log filename:level\fR
Emit trace to the specified file. The level is a verbosity level from 0-5 with 5 being the most verbose. 

.TP 10
\fB\--noclean\fR
Do not clean the 'dist' directory before rendering. By default Expansive will remove all the content under 'dist' first.

.TP 10
\fB\--norender\fR
Do not do an initial render before watching for changes.

.TP 10
\fB\--nowatch\fR
Do not watch for changes when serving content.

.TP 10
\fB\--quiet\fR
Run in quiet mode. Do not emit activity trace to the console.

.TP 10
\fB\--trace filename:level\fR
Trace HTTP requests to the specified file. The level is a verbosity level from 0-5 with 5 being the most verbose.
HTTP requests and HTTP headers will be traced at levels 2-4.

.TP 10
\fB\--verbose\fR
Run in verbose mode. Emit more activity trace.

.TP 10
\fB\--versions URI\fR
Show expansive version information.

.TP 10
\fB\--DIGIT
Emit log and HTTP trace to stderr at the specified level. The DIGIT must be 0 to 5 with 5 being the most verbose.
This option is the same as "--log stderr:DIGIT --trace stderr:DIGIT"

.PP
.SH "REPORTING BUGS"
Report bugs to dev@embedthis.com.
.SH COPYRIGHT
Copyright \(co Embedthis Software. MakeMe, Pak and Ejscript are a trademarks of Embedthis Software.
.br
.SH "SEE ALSO"
ejs, esp, me, pak, http://embedthis.com/expansive/
